Skip to content

doctest(feat[HIDE]): Register no-op +HIDE optionflag#79

Merged
tony merged 2 commits into
masterfrom
doctest-hide-badges
Jul 14, 2026
Merged

doctest(feat[HIDE]): Register no-op +HIDE optionflag#79
tony merged 2 commits into
masterfrom
doctest-hide-badges

Conversation

@tony

@tony tony commented Jul 14, 2026

Copy link
Copy Markdown
Member

What

Register a HIDE doctest optionflag so an example can be marked # doctest: +HIDE. HIDE is a no-op for execution — the output checker never consults it — but without registration, # doctest: +HIDE raises ValueError: ... invalid option: '+HIDE' at collection time.

Registration is eager (in pytest_configure, before collection), because the .py docstring path delegates to pytest's own DoctestModule, which never calls this plugin's _get_flag_lookup.

Why

Documentation tooling (a Sphinx autodoc-process-docstring hook in gp-sphinx) can then drop +HIDE-marked setup lines from rendered output while the doctest runner still executes them — the runner reads __doc__ from source, untouched by the render strip. This lets a docstring run incidental plumbing (building an env mapping, a socket path) without cluttering the reader-facing docs.

Tests

test_hide_optionflag_py_docstring: a .py docstring carrying # doctest: +HIDE collects and runs as a no-op.

Part of a coordinated set with gp-sphinx (the render-side strip) and a downstream consumer that adopts the marker.

why: Let documentation tooling mark a doctest example to hide from
rendered output while it still runs as a real test. Without the
registration, `# doctest: +HIDE` raises ValueError: invalid option at
collection time.

what:
- Register HIDE eagerly in pytest_configure, before collection. The .py
  docstring path delegates to pytest's own DoctestModule, which never
  calls our _get_flag_lookup, so import-time registration is load-bearing.
- Add _get_hide_flag() and a HIDE entry in _get_flag_lookup for the
  .rst/.md path and ini use.
- Test: `# doctest: +HIDE` in a .py docstring collects and runs as a no-op.
@codecov

codecov Bot commented Jul 14, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 90.90909% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 76.32%. Comparing base (2205f4d) to head (a4e20e3).

Files with missing lines Patch % Lines
src/pytest_doctest_docutils.py 75.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master      #79      +/-   ##
==========================================
+ Coverage   76.16%   76.32%   +0.15%     
==========================================
  Files          15       15              
  Lines        1007     1018      +11     
==========================================
+ Hits          767      777      +10     
- Misses        240      241       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@tony tony changed the title doctest(feat[HIDE]): Register no-op HIDE optionflag doctest(feat[HIDE]): Register no-op +HIDE optionflag Jul 14, 2026
tony added a commit to tmux-python/libtmux that referenced this pull request Jul 14, 2026
why: The socket_path/env plumbing that opens each from_env example is
needed for the doctest to execute but is noise to the reader. Marking it
hidden runs it as a test while keeping it out of the rendered docs.

what:
- Tag the setup lines in Server/Window/Pane.from_env with
  `# doctest: +HIDE`; split the env dicts so the marker fits <=88 cols.
- Session.from_env hides only socket_path — its env carries the
  deliberately wrong session id the surrounding prose explains, so it
  stays visible (hide plumbing, not meaning).
- TEMP: pin gp-libs / gp-sphinx to the branches carrying the HIDE
  optionflag and the render strip (git-pull/gp-libs#79,
  git-pull/gp-sphinx#65) via [tool.uv.sources]; revert to releases once
  they land.
tony added a commit to tmux-python/libtmux that referenced this pull request Jul 14, 2026
why: The socket_path/env plumbing that opens each from_env example is
needed for the doctest to execute but is noise to the reader. Marking it
hidden runs it as a test while keeping it out of the rendered docs.

what:
- Tag the setup lines in Server/Window/Pane.from_env with
  `# doctest: +HIDE`; split the env dicts so the marker fits <=88 cols.
- Session.from_env hides only socket_path — its env carries the
  deliberately wrong session id the surrounding prose explains, so it
  stays visible (hide plumbing, not meaning).
- TEMP: git-branch-pin the three changed packages (gp-libs,
  sphinx-autodoc-api-style, sphinx-autodoc-typehints-gp) to
  doctest-hide-badges; add typehints-gp as a direct dep so uv honors its
  source pin (uv.sources applies to direct deps only). gp-sphinx and its
  JS-asset packages stay on PyPI wheels, so CI needn't build the
  vite/pnpm toolchain. Revert to releases once git-pull/gp-libs#79 and
  git-pull/gp-sphinx#65 publish.
why: Document the new +HIDE marker for the unreleased section.

what:
- Add "New doctest flag: +HIDE" under What's new
@tony tony merged commit 2e8c723 into master Jul 14, 2026
36 checks passed
@tony tony deleted the doctest-hide-badges branch July 14, 2026 00:50
tony added a commit that referenced this pull request Jul 14, 2026
why: The +HIDE marker shipped in #79 with only a CHANGES entry; the
docs site had no how-to explaining when or why to reach for it.

what:
- Add a "Hide a setup line from rendered docs" section to the pytest
  plugin how-to, with a runnable example the docs suite executes
- Note the marker parses under the pytest plugin (.rst, .md, .py) but
  not the standalone doctest_docutils CLI
tony added a commit to git-pull/gp-sphinx that referenced this pull request Jul 14, 2026
…ier (#65)

Two independent API-documentation polish changes. One hides incidental
doctest setup from rendered autodoc output while the example still runs
as a test; the other stops class-member modifiers from rendering twice.

- **Hide `+HIDE` doctest setup** (`typehints-gp`): doctest lines tagged
  `# doctest: +HIDE` are dropped from the rendered docstring, along with
  their `...` continuations, so plumbing like an `env` mapping or a
  socket path executes without cluttering the example. The strip runs
  at Sphinx build time; the source docstring — and the test that runs
  from it — is untouched.
- **Fix double-rendered modifiers** (`api-style`): members marked
  `classmethod`, `staticmethod`, `async`, or `abstract` showed the
  modifier twice — once as a signature prefix, once as the badge beside
  it. The redundant prefix is dropped so each modifier appears only in
  its badge; `property`/`type` word prefixes are left untouched.
- **Documentation**: the `typehints-gp` how-to gains a "Hiding
  incidental doctest setup" section covering the flag and the
  doctest-runner registration it needs.

See also: git-pull/gp-libs#79
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant